Problem
This repository uses local Nx plugins and async generators written in TypeScript that need to:

• Import files with .js extensions (ES modules convention)
• Resolve TypeScript path aliases (e.g., @code-pushup/models)

Without proper TypeScript execution setup, Nx commands fail when trying to execute these local plugins/generators.

Solution
Explicit environment variable configuration for both local development and CI:

• Local Development - Use .env.local (gitignored)
• Developers copy .env.local.example to .env.local
• Nx automatically loads .env.local files
• CI - Set environment variables explicitly at workflow level
  • NODE_OPTIONS=--import tsx - Enables TypeScript execution
  • TSX_TSCONFIG_PATH=tsconfig.base.json - Resolves path aliases

Background

Why SWC is skipped when running Nx with NODE_OPTIONS="--import tsx"

Nx has hardcoded transpiler-selection logic for local TS/TSX execution (plugins, executors, generators).
When running with a Node loader like tsx, Nx does not register SWC, even if SWC is available.

Relevant source:
https://github.com/nrwl/nx/blob/81c157d0631927b3d1891453aa45652f3b5a7988/packages/nx/src/plugins/js/utils/register.ts

Key logic:

export function registerTranspiler(
  compilerOptions: CompilerOptions,
  tsConfigRaw?: unknown
): () => void {
  const transpiler = getTranspiler(compilerOptions, tsConfigRaw);

  if (!transpiler) {
    warnNoTranspiler();
    return () => {};
  }

  return transpiler();
}

If getTranspiler(...) returns undefined, Nx intentionally does not register SWC or ts-node.

getTranspiler(...) only detects:

• @swc-node/register
• ts-node

Node loaders like tsx are not detected, so:

• getTranspiler(...) === undefined
• registerTranspiler becomes a no-op
• SWC is effectively disabled by design for this execution path

This is not in @nx/js:swc, but in Nx’s runtime TS/TSX plugin execution pipeline.
Running with NODE_OPTIONS="--import tsx" therefore bypasses SWC via hardcoded logic.

Related:

• refactor: add sync generator for zod2md tooling setup #1188
• refactor: add sync generator for zod2md tooling setup #1188 (comment)